.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH MSERVER5 1 "APRIL 2011" MonetDB "MonetDB Applications"
.SH NAME
mserver5 \- the MonetDB server version 5
.SH SYNOPSIS
.B mserver5
[
.I options
]
.SH DESCRIPTION
.I Mserver5
is the current MonetDB server that performs all processing on request
of clients for a certain database.
.P
Note that while
.I mserver5
is the process that does the actual work, it is usually more common to
start, monitor and connect to the
.I mserver5
process through
.IR monetdbd (1).
.P
This man-page describes the options that
.I mserver5
understands.
It is intended for people who really need to work with
.I mserver5
itself.
In regular cases, the programs
.IR monetdbd (1)
and
.IR monetdb (1)
control the many options, and allow to adjust them to appropriate
values where sensible.
For normal usage, it is preferred to apply any configuration through
these programs.
.SH OPERATION
When the build-time configuration did not disable this, a
.I mserver5
process presents the user with a console prompt.
On this prompt, MAL commands can be executed.  The architecture is
setup to handle multiple streams of requests.
The first thread started represents the server, which is the console
prompt, reading from standard input and writing to standard output.
.P
The server thread started remains in existence until all other threads
die.
The server is stopped by Ctrl-D on its console, typing
.B quit()
or by sending it a termination signal (SIGINT, SIGTERM, SIGQUIT).
.SH MSERVER5 OPTIONS
.I Mserver5
can be started with options and scripts as arguments.
The MAL scripts will be executed directly after startup on the
console, which eases e.g. testing of MAL scripts directly, without
starting a client.
.TP
\fB\-\-dbpath=\fP\fIpath\fP
Path where
.I mserver5
should find a database.
Shorthand for option
.BR gdk_dbpath .
Default value:
.BR @localstatedir@/monetdb5/dbfarm/demo .
.TP
\fB\-\-dbextra=\fP\fIpath\fP
Path where mserver5 should store transient data.  Default value is the
value of the
.B \-\-dbpath
option.
.TP
\fB\-\-dbinit=\fP\fIstmt\fP
MAL statement to execute as part of the startup of the server.
.TP
\fB\-\-config=\fP\fIfile\fP
Config file to read options from.
This file can contain all options as can be set with the --set flag.
See
.IR "CONFIG FILE FORMAT" .
.TP
.B \-\-daemon=yes
.PD 0
.B \-\-daemon=no
.PD
Disable the console prompt, do not read commands from standard input.
Default:
.BR no .
.TP
\fB\-\-set\fP \fIoption\fP\fB=\fP\fIvalue\fP
Set individual configuration option.
For possible options, see
.I PARAMETERS
sections.
.TP
.B \-\-help
Print list of options.
.TP
.B \-\-version
Print version and compile configuration.
.SH GDK PARAMETERS
GDK (Goblin Database Kernel) is the current columnar storage kernel
engine of the MonetDB 5 database.
It is the component that manages and performs operations on BATs
(Binary Association Tables), single columns.
The parameters here affect the behaviour of GDK which may nagatively
impact performance if set wrongly.
The kernel tries to choose the values for optimal performance.
Changing these parameters is discouraged.
.P
.TP
.B gdk_vmtrim
Enable or disable the vmtrim thread which tries to unload memory that
is not in use.
Default:
.B yes
on 32 bit platforms,
.B no
on 64 bit platforms
.TP
.B gdk_debug
You can enable debug output for specific kernel operations.
By default debug is switched off for obvious reasons.
The value of gdk_debug is an integer, which value can be (a
combination of):
.EX
          1 = THRDMASK     = thread-specific debug output
          2 = CHECKMASK    = property enforcing on new BATs
          4 = MEMMASK      = memory allocation
          8 = PROPMASK     = property checking on all values:
                             tells about wrongly set properties
         16 = IOMASK       = major IO activity
         32 = BATMASK      = BAT handling
.\"         64 = PARSEMASK    = parser debugging
        128 = PARMASK      = Thread management
        256 = HEADLESSMASK = Warn about BAT heads that are not "headless-ready"
        512 = TMMASK       = Transaction management
       1024 = TEMMASK      = Locks and Triggers
.\"       2048 = DLMASK       = Dynamic loading
       4096 = PERFMASK     = BBP Performance (?)
       8192 = DELTAMASK    = Delta debugging (?)
      16384 = LOADMASK     = Module loading
.\"      32768 = YACCMASK     = Yacc specific error messages
    2097152 = ALGOMASK     = show join/select algorithm chosen
    4194304 = ESTIMASK     = show result size estimations
                             (for join, select)
.\"    8388608 = XPROPMASK    = extended property checking:
.\"                             tells also about not set properties
   16777216 = JOINPROPMASK = disable property checking with
                             join & outerjoin (e.g., for
                             performance measurements)
   33554432 = DEADBEEFMASK = disable "cleaning" of freed memory
                             in GDKfree() (e.g., for performance
                             measurements)
   67108864 = ALLOCMASK    = exhaustive GDK malloc & free tracing
                             for debugging (GDK developers, only)
  134217728 = OPTMASK      = trace the actions, decisions and
                             effects of MAL optimizers
  268435456 = HEAPMASK     = trace/debug HEAPextend;
                             used only for development & debugging
  536870912 = FORCEMITOMASK = forcefully activate mitosis even on
                              small tables, i.e., split small tables
                              in as many (tiny) pieces as there are
                              cores (threads) available;
                              this allows us to test mitosis
                              functionality without requiring large
                              data sets (\(em at the expense of a
                              potentially significant interpretation
                              overhead for unnecessarily large plans);
                              used only for development & testing;
                              set automatically by Mtest.py
.EE

Note that
.I mserver5
recognizes a series of command line options that sets one or more of
these debug flags as well:
.EX
  \-\-threads       (THRDMASK | PARMASK)
  \-\-memory        (MEMMASK | ALLOCMASK)
  \-\-properties    (CHECKMASK | PROPMASK | BATMASK)
  \-\-io            (IOMASK | PERFMASK)
  \-\-heaps         (HEAPMASK)
  \-\-transactions  (TMMASK | DELTAMASK | TEMMASK)
  \-\-modules       (LOADMASK)
  \-\-algorithms    (ALGOMASK | ESTIMASK)
  \-\-performance   (JOINPROPMASK | DEADBEEFMASK)
  \-\-optimizers    (OPTMASK)
  \-\-forcemito     (FORCEMITOMASK)
  \-\-trace[=stethoscope argument]
.EE

Default:
.BR 0 .
.SH MSERVER5 PARAMETERS
.I Mserver5
instructs the GDK kernel through the MAL (MonetDB Assembler Language)
language.
MonetDB 5 contains an extensive optimiser framework to transform MAL
plans into more optimal or functional (e.g.  distributed) plans.
These parameters control behaviour on the MAL level.
.TP
.B mal_listing
You can enable the server listing the parsed MAL program for any
script parsed on the command line.
The value of mal_listing is an integer that have the following
possible values:
.EX
   0 = Disable
   1 = List the original input
   2 = List the MAL instruction
   4 = List the MAL type information
   8 = List the MAL UDF type
  16 = List the MAL properties
  32 = List the hidden details
  64 = List the bat tuple count
.EE

Default:
.BR 0 .
.TP
.B monet_vault_key
The authorisation tables inside
.I mserver5
can be encrypted with a key, such that reading the BATs does not
directly disclose any credentials.
The
.B monet_vault_key
setting points to a file that stores a secret key to unlock the
password vault.
It can contain anything.
The file is read up to the first null-byte ('\0'), hence it can be
padded to any length with trailing null-bytes to obfuscate the key
length.
Generating a key can be done for example by using a tool such as
.I pwgen
and adding a few of the passwords generated.
Make sure not to choose a too small key.
Note that on absence of a vault key file, some default key is used to
encrypt the authorisation tables.
Changing this setting (effectively changing the key) for an existing
database makes that database unusable as noone is any longer able to
login.
If you use
.IR monetdbd (1),
a per-database vault key is set.
.TP
.B max_clients
Controls how many client slots are allocated for clients to connect.
This settings limits the maximum number of connected clients at the
same time.
Note that MonetDB is not designed to handle massive amounts of
connected clients.
The funnel capability from
.IR monetdbd (1)
might be a more suitable solution for such workloads.

Default
.BR 64 .
.SH SQL PARAMETERS
The SQL component of MonetDB 5 runs on top of the MAL environment.
It has its own SQL-level specific settings.
.TP
.B sql_debug
Enable debugging using a mask.
This option should normally be disabled (0).
Default:
.BR 0 .
.TP
.B sql_optimizer
The default SQL optimizer pipeline can be set per server.
See the optpipe setting in
.IR monetdb (1)
when using monetdbd.
During SQL initialization, the optimizer pipeline is checked against
the dependency information maintained in the optimizer library to
ensure there are no conflicts and at least the pre-requisite
optimizers are used.
The setting of sql_optimizer can be either the list of optimizers to
run, or one or more variables containing the optimizer pipeline to
run.
The latter is provided for readability purposes only.
Default:
.BR default_pipe .
.P
The following are possible pipes to use:
.TP
.B minimal_pipe
The minimal pipeline necessary by the server to operate correctly.
.\" this documentation must be kept in sync with the respective code in monetdb5/optimizer/opt_pipes.c
minimal_pipe=inline,remap,deadcode,multiplex,garbageCollector
.TP
.B default_pipe
The default pipe line contains the mitosis-mergetable-reorder
optimizers, aimed at large tables and improved access locality.
.\" this documentation must be kept in sync with the respective code in monetdb5/optimizer/opt_pipes.c
default_pipe=inline,remap,costModel,coercions,evaluate,emptySet,aliases,pushselect,mitosis,mergetable,deadcode,commonTerms,joinPath,reorder,deadcode,reduce,matpack,dataflow,querylog,multiplex,garbageCollector
.TP
.B no_mitosis_pipe
The no_mitosis pipe line is identical to the default pipeline, except
that optimizer mitosis is omitted.
It is used mainly to make some tests work deterministically, and to
check/debug whether "unexpected" problems are related to mitosis
(and/or mergetable).
.\" this documentation must be kept in sync with the respective code in monetdb5/optimizer/opt_pipes.c
no_mitosis_pipe=inline,remap,costModel,coercions,evaluate,emptySet,aliases,pushselect,mergetable,deadcode,commonTerms,joinPath,reorder,deadcode,reduce,matpack,dataflow,querylog,multiplex,garbageCollector
.TP
.B sequential_pipe
The sequential pipe line is identical to the default pipeline, except
that optimizers mitosis & dataflow are omitted.
It is use mainly to make some tests work deterministically, i.e.,
avoid ambigious output, by avoiding parallelism.
.\" this documentation must be kept in sync with the respective code in monetdb5/optimizer/opt_pipes.c
sequential_pipe=inline,remap,costModel,coercions,evaluate,emptySet,aliases,pushselect,mergetable,deadcode,commonTerms,joinPath,reorder,deadcode,reduce,matpack,querylog,multiplex,garbageCollector
.SH CONFIG FILE FORMAT
The configuration file readable by
.I mserver5
consists of parameters of the form \(dq\&\fIname\fP=\fIvalue\fP\(dq\&.
The file is line-based, each newline-terminated line represents either
a comment or a parameter.
Only the first equals sign in a parameter is significant.
Whitespace before or after the first equals sign is not stripped.
Trailing whitespace in a parameter value is retained verbatim.
Any line beginning with a hash
.RB ( # )
is ignored, as are lines containing only whitespace.
The values following the equals sign in parameters are all a string
where quotes are not needed, and if written be part of the string.
.SH SEE ALSO
.IR monetdbd (1),
.IR monetdb (1),
.IR mclient (1)
